<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="datetime-datetime.html" />
<link rel="prev" href="datetime-timedelta.html" />
<link rel="parent" href="module-datetime.html" />
<link rel="next" href="datetime-datetime.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>5.1.3 date Objects </title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.1.2 timedelta Objects"
  href="datetime-timedelta.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="5.1 datetime  "
  href="module-datetime.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="5.1.4 datetime Objects"
  href="datetime-datetime.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="datetime-timedelta.html">5.1.2 timedelta Objects</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-datetime.html">5.1 datetime  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="datetime-datetime.html">5.1.4 datetime Objects</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION007130000000000000000"></a><a name="datetime-date"></a>
<br>
5.1.3 <tt class="class">date</tt> Objects 
</h2>

<p>
A <tt class="class">date</tt> object represents a date (year, month and day) in an idealized
calendar, the current Gregorian calendar indefinitely extended in both
directions.  January 1 of year 1 is called day number 1, January 2 of year
1 is called day number 2, and so on.  This matches the definition of the
"proleptic Gregorian" calendar in Dershowitz and Reingold's book
<em class="citetitle"
 >Calendrical Calculations</em>, where it's the base calendar for all
computations.  See the book for algorithms for converting between
proleptic Gregorian ordinals and many other calendar systems.

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-614' xml:id='l2h-614' class="class">date</tt></b>(</nobr></td>
  <td><var>year, month, day</var>)</td></tr></table></dt>
<dd>
  All arguments are required.  Arguments may be ints or longs, in the
  following ranges:

<p>

<ul>
<li><code>MINYEAR &lt;= <var>year</var> &lt;= MAXYEAR</code>
</li>
<li><code>1 &lt;= <var>month</var> &lt;= 12</code>
</li>
<li><code>1 &lt;= <var>day</var> &lt;= number of days in the given month and year</code>
  
</li>
</ul>

<p>
If an argument outside those ranges is given, <tt class="exception">ValueError</tt>
  is raised.
</dl>

<p>
Other constructors, all class methods:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-615' xml:id='l2h-615' class="method">today</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return the current local date.  This is equivalent to
  <code>date.fromtimestamp(time.time())</code>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-616' xml:id='l2h-616' class="method">fromtimestamp</tt></b>(</nobr></td>
  <td><var>timestamp</var>)</td></tr></table></dt>
<dd>
  Return the local date corresponding to the POSIX timestamp, such
  as is returned by <tt class="function">time.time()</tt>.  This may raise
  <tt class="exception">ValueError</tt>, if the timestamp is out of the range of
  values supported by the platform C <tt class="cfunction">localtime()</tt>
  function.  It's common for this to be restricted to years from 1970
  through 2038.  Note that on non-POSIX systems that include leap
  seconds in their notion of a timestamp, leap seconds are ignored by
  <tt class="method">fromtimestamp()</tt>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-617' xml:id='l2h-617' class="method">fromordinal</tt></b>(</nobr></td>
  <td><var>ordinal</var>)</td></tr></table></dt>
<dd>
  Return the date corresponding to the proleptic Gregorian ordinal,
  where January 1 of year 1 has ordinal 1.  <tt class="exception">ValueError</tt> is
  raised unless <code>1 &lt;= <var>ordinal</var> &lt;= date.max.toordinal()</code>.
  For any date <var>d</var>, <code>date.fromordinal(<var>d</var>.toordinal()) ==
  <var>d</var></code>.
</dl>

<p>
Class attributes:

<p>
<dl><dt><b><tt id='l2h-618' xml:id='l2h-618' class="member">min</tt></b></dt>
<dd>
  The earliest representable date, <code>date(MINYEAR, 1, 1)</code>.
</dl>

<p>
<dl><dt><b><tt id='l2h-619' xml:id='l2h-619' class="member">max</tt></b></dt>
<dd>
  The latest representable date, <code>date(MAXYEAR, 12, 31)</code>.
</dl>

<p>
<dl><dt><b><tt id='l2h-620' xml:id='l2h-620' class="member">resolution</tt></b></dt>
<dd>
  The smallest possible difference between non-equal date
  objects, <code>timedelta(days=1)</code>.
</dl>

<p>
Instance attributes (read-only):

<p>
<dl><dt><b><tt id='l2h-621' xml:id='l2h-621' class="member">year</tt></b></dt>
<dd>
  Between <tt class="constant">MINYEAR</tt> and <tt class="constant">MAXYEAR</tt> inclusive.
</dl>

<p>
<dl><dt><b><tt id='l2h-622' xml:id='l2h-622' class="member">month</tt></b></dt>
<dd>
  Between 1 and 12 inclusive.
</dl>

<p>
<dl><dt><b><tt id='l2h-623' xml:id='l2h-623' class="member">day</tt></b></dt>
<dd>
  Between 1 and the number of days in the given month of the given
  year.
</dl>

<p>
Supported operations:

<p>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="center">Operation</th>
      <th class="left"  >Result</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="center" valign="baseline"><code><var>date2</var> = <var>date1</var> + <var>timedelta</var></code></td>
        <td class="left"  ><var>date2</var> is <code><var>timedelta</var>.days</code> days removed from
    <var>date1</var>.  (1)</td></tr><p>

    <tr><td class="center" valign="baseline"><code><var>date2</var> = <var>date1</var> - <var>timedelta</var></code></td>
        <td class="left"  >Computes <var>date2</var> such that <code><var>date2</var> + <var>timedelta</var>
   == <var>date1</var></code>. (2)</td></tr><p>

    <tr><td class="center" valign="baseline"><code><var>timedelta</var> = <var>date1</var> - <var>date2</var></code></td>
        <td class="left"  >(3)</td></tr><p>

    <tr><td class="center" valign="baseline"><code><var>date1</var> &lt; <var>date2</var></code></td>
        <td class="left"  ><var>date1</var> is considered less than <var>date2</var> when <var>date1</var>
   precedes <var>date2</var> in time. (4)</td></tr><p>

    </tbody>
</table></div>

<p>
Notes:
<dl>
<dt><strong>(1)</strong></dt>
<dd><var>date2</var> is moved forward in time if <code><var>timedelta</var>.days
    &gt; 0</code>, or backward if <code><var>timedelta</var>.days &lt; 0</code>.  Afterward
    <code><var>date2</var> - <var>date1</var> == <var>timedelta</var>.days</code>.
    <code><var>timedelta</var>.seconds</code> and
    <code><var>timedelta</var>.microseconds</code> are ignored.
    <tt class="exception">OverflowError</tt> is raised if <code><var>date2</var>.year</code>
    would be smaller than <tt class="constant">MINYEAR</tt> or larger than
    <tt class="constant">MAXYEAR</tt>.

<p>
</dd>
<dt><strong>(2)</strong></dt>
<dd>This isn't quite equivalent to date1 +
   (-timedelta), because -timedelta in isolation can overflow in cases
   where date1 - timedelta does not.  <code><var>timedelta</var>.seconds</code>
   and <code><var>timedelta</var>.microseconds</code> are ignored.

<p>
</dd>
<dt><strong>(3)</strong></dt>
<dd>This is exact, and cannot overflow.  timedelta.seconds and
    timedelta.microseconds are 0, and date2 + timedelta == date1
    after.

<p>
</dd>
<dt><strong>(4)</strong></dt>
<dd>In other words, <code>date1 &lt; date2</code>
   if and only if <code><var>date1</var>.toordinal() &lt;
   <var>date2</var>.toordinal()</code>.
In order to stop comparison from falling back to the default
scheme of comparing object addresses, date comparison
normally raises <tt class="exception">TypeError</tt> if the other comparand
isn't also a <tt class="class">date</tt> object.  However, <code>NotImplemented</code>
is returned instead if the other comparand has a
<tt class="method">timetuple</tt> attribute.  This hook gives other kinds of
date objects a chance at implementing mixed-type comparison.
If not, when a <tt class="class">date</tt> object is
compared to an object of a different type, <tt class="exception">TypeError</tt> is
raised unless the comparison is <code>==</code> or <code>!=</code>.  The latter
cases return <tt class="constant">False</tt> or <tt class="constant">True</tt>, respectively.

<p>
</dd>
</dl>

<p>
Dates can be used as dictionary keys. In Boolean contexts, all
<tt class="class">date</tt> objects are considered to be true.

<p>
Instance methods:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-624' xml:id='l2h-624' class="method">replace</tt></b>(</nobr></td>
  <td><var>year, month, day</var>)</td></tr></table></dt>
<dd>
  Return a date with the same value, except for those members given
  new values by whichever keyword arguments are specified.  For
  example, if <code>d == date(2002, 12, 31)</code>, then
  <code>d.replace(day=26) == date(2002, 12, 26)</code>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-625' xml:id='l2h-625' class="method">timetuple</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return a <tt class="class">time.struct_time</tt> such as returned by
  <tt class="function">time.localtime()</tt>.  The hours, minutes and seconds are
  0, and the DST flag is -1.
  <code><var>d</var>.timetuple()</code> is equivalent to
      <code>time.struct_time((<var>d</var>.year, <var>d</var>.month, <var>d</var>.day,
             0, 0, 0,
             <var>d</var>.weekday(),
             <var>d</var>.toordinal() - date(<var>d</var>.year, 1, 1).toordinal() + 1,
            -1))</code>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-626' xml:id='l2h-626' class="method">toordinal</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return the proleptic Gregorian ordinal of the date, where January 1
  of year 1 has ordinal 1.  For any <tt class="class">date</tt> object <var>d</var>,
  <code>date.fromordinal(<var>d</var>.toordinal()) == <var>d</var></code>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-627' xml:id='l2h-627' class="method">weekday</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return the day of the week as an integer, where Monday is 0 and
  Sunday is 6.  For example, <code>date(2002, 12, 4).weekday() == 2</code>, a
  Wednesday.
  See also <tt class="method">isoweekday()</tt>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-628' xml:id='l2h-628' class="method">isoweekday</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return the day of the week as an integer, where Monday is 1 and
  Sunday is 7.  For example, <code>date(2002, 12, 4).isoweekday() == 3</code>, a
  Wednesday.
  See also <tt class="method">weekday()</tt>, <tt class="method">isocalendar()</tt>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-629' xml:id='l2h-629' class="method">isocalendar</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return a 3-tuple, (ISO year, ISO week number, ISO weekday).

<p>
The ISO calendar is a widely used variant of the Gregorian calendar.
  See <a class="url" href="http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm">http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm</a>  for a good explanation.

<p>
The ISO year consists of 52 or 53 full weeks, and where a week starts
  on a Monday and ends on a Sunday.  The first week of an ISO year is
  the first (Gregorian) calendar week of a year containing a Thursday.
  This is called week number 1, and the ISO year of that Thursday is
  the same as its Gregorian year.

<p>
For example, 2004 begins on a Thursday, so the first week of ISO
  year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan
  2004, so that
  <code>date(2003, 12, 29).isocalendar() == (2004, 1, 1)</code>
  and
  <code>date(2004, 1, 4).isocalendar() == (2004, 1, 7)</code>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-630' xml:id='l2h-630' class="method">isoformat</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return a string representing the date in ISO 8601 format,
  'YYYY-MM-DD'.  For example,
  <code>date(2002, 12, 4).isoformat() == '2002-12-04'</code>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-631' xml:id='l2h-631' class="method">__str__</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  For a date <var>d</var>, <code>str(<var>d</var>)</code> is equivalent to
  <code><var>d</var>.isoformat()</code>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-632' xml:id='l2h-632' class="method">ctime</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Return a string representing the date, for example
  date(2002, 12, 4).ctime() == 'Wed Dec  4 00:00:00 2002'.
  <code><var>d</var>.ctime()</code> is equivalent to
  <code>time.ctime(time.mktime(<var>d</var>.timetuple()))</code>
  on platforms where the native C <tt class="cfunction">ctime()</tt> function
  (which <tt class="function">time.ctime()</tt> invokes, but which
  <tt class="method">date.ctime()</tt> does not invoke) conforms to the C standard.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-633' xml:id='l2h-633' class="method">strftime</tt></b>(</nobr></td>
  <td><var>format</var>)</td></tr></table></dt>
<dd>
  Return a string representing the date, controlled by an explicit
  format string.  Format codes referring to hours, minutes or seconds
  will see 0 values.
  See section&nbsp;<a href="strftime-behavior.html#strftime-behavior">5.1.7</a> - <tt class="method">strftime()</tt> behavior.
</dl>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.1.2 timedelta Objects"
  href="datetime-timedelta.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="5.1 datetime  "
  href="module-datetime.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="5.1.4 datetime Objects"
  href="datetime-datetime.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="datetime-timedelta.html">5.1.2 timedelta Objects</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-datetime.html">5.1 datetime  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="datetime-datetime.html">5.1.4 datetime Objects</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
